﻿////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// <copyright>Copyright 2008-2011 Andreas Huber Doenni</copyright>
// Distributed under the Microsoft Public License (Ms-PL).
// See accompanying file License.txt or copy at http://mews.codeplex.com/license.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

namespace Mews.Net.Nntp.Cache
{
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.Diagnostics.CodeAnalysis;
    using System.Security.Cryptography;

    /// <summary>Represents NNTP host.</summary>
    /// <threadsafety static="true" instance="false"/>
    public interface IHost : IDeletablePersistentObject, IEquatable<IHost>
    {
        /// <summary>Gets the network name of the host.</summary>
        string Name
        {
            get;
        }

        /// <summary>Gets the port of the host.</summary>
        int Port
        {
            get;
        }

        /// <summary>Gets or sets the posting user name for the host.</summary>
        /// <exception cref="ArgumentException">Attempted to set a value the length of which exceeds the maximum allowed
        /// length.</exception>
        string UserName
        {
            get;
            set;
        }

        /// <summary>Gets or sets the posting email address for the host.</summary>
        /// <exception cref="ArgumentException">Attempted to set a value the length of which exceeds the maximum allowed
        /// length.</exception>
        string EmailAddress
        {
            get;
            set;
        }

        /// <summary>Gets or sets the logon account name for the host.</summary>
        /// <exception cref="ArgumentException">Attempted to set a value the length of which exceeds the maximum allowed
        /// length.</exception>
        /// <exception cref="CryptographicException">The account name could not be decrypted. This usually happens when
        /// a different user attempts to get the account name than the one who has set it.</exception>
        string AccountName
        {
            get;
            set;
        }

        /// <summary>Gets or sets the logon password for the host.</summary>
        /// <exception cref="ArgumentException">Attempted to set a value the length of which exceeds the maximum allowed
        /// length.</exception>
        /// <exception cref="CryptographicException">The password could not be decrypted. This usually happens when
        /// a different user attempts to get the password than the one who has set it.</exception>
        string Password
        {
            get;
            set;
        }

        /// <summary>Adds a new group to the cache and returns an object representing the group.</summary>
        /// <param name="groupName">The NNTP name of the group.</param>
        /// <param name="groupDisplayName">The display name of the group.</param>
        /// <param name="newInboundArticlesReceiveLimit">The maximum number of new articles for which information is
        /// received during each send/receive operation started with <see cref="Cache.StartSendReceive"/>.</param>
        /// <param name="cachedInboundArticlesLimit">The maximum number of articles that are held in the cache.</param>
        /// <exception cref="ArgumentException">The length of <paramref name="groupName"/> or
        /// <paramref name="groupDisplayName"/> exceeds the maximum allowed length, or the cache already contains a
        /// group with the same name that is associated with this host.</exception>
        /// <exception cref="ArgumentNullException"><paramref name="groupName"/> and/or
        /// <paramref name="groupDisplayName"/> equal <c>null</c>.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><list type="bullet">
        /// <item><paramref name="newInboundArticlesReceiveLimit"/> is 0 or negative; or</item>
        /// <item><paramref name="cachedInboundArticlesLimit"/> is less than
        /// <paramref name="newInboundArticlesReceiveLimit"/>.</item>
        /// </list></exception>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object, or, <see cref="IDeletablePersistentObject.Delete"/> has been called on this
        /// object or its parent <see cref="IHost"/> object.</exception>
        IGroup AddGroup(
            string groupName,
            string groupDisplayName,
            int newInboundArticlesReceiveLimit,
            int cachedInboundArticlesLimit);

        /// <summary>Gets the groups that have been added to this host with <see cref="AddGroup"/>.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object.</exception>
        /// <remarks>The documented exceptions are never thrown from this method but from the
        /// <see cref="IEnumerator.MoveNext"/> method.</remarks>
        [SuppressMessage("Microsoft.Design", "CA1024:UsePropertiesWhereAppropriate", Justification = "This is an expensive operation.")]
        IEnumerable<IGroup> GetGroups();

        /// <summary>Adds a new outbound article to the cache and returns an object representing the article.</summary>
        /// <exception cref="InvalidOperationException"><see cref="Cache.Dispose"/> has been called on the parent
        /// <see cref="Cache"/> object, or, <see cref="IDeletablePersistentObject.Delete"/> has been called on this
        /// object or its parent <see cref="IHost"/> object.</exception>
        IOutboundArticle AddOutboundArticle();
    }
}
